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ABSTRACT and CONTENTS 

The debugging language for the Ml Compiler System is described 
in detail sufficient for the user. Informal syntax and seman- 
tics are given for all commands, including a careful treatment 
of possible program states with respect to suspended tasks. 
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The command processor will exist at any time in one of several 

modes. These are: 

executive & 

verbose editor * 

quick editor \:\ 

expert debugger h 

beginner debugger ?=\ 

Each of these modes will have its own herald as indicated. 

SPL is entered in executive mode and will thus type an & • 

To change modes merely type the herald for the desired mode 
immediately after another herald and continue. This new 
mode will stick until another herald is typed. 

The executive and editor modes will be discussed elsewhere. 
The debugger is now described. 

A command in beginner mode is Of the general form 
=<command> [<modifiers>; ] [arguments] 

By <command> is meant a sufficient number of characters to 
distinguish the command from all others, terminated by a 
blank. The modifiers are a collection of single letters 
terminated by a colon. The nature of the arguments depend on 
the command . The. entire command is terminated by a carriage 
return. 

A command in expert mode is of the general form 
~[<modif iers>] <command> [<args>] 

The command will be a single punctuation character and will 
thus serve to terminate the modifiers and eliminates the need 
to type a blank after the command. 
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Command descriptors 

MODE '■■■...;.#■ 

This command takes no arguments (other than modifiers) and sets 

the debugger permanently into all the specified modes. 

GOTO $ 

Takes two optional arguments. First is the editor address of 

the statements to transfer control to. Second is number of 

break points to pass through before control is returned to the 

debugger. 

CONTINUE , 

Takes one optional argument, the number .of break points to pass 
through. This command will ignore a break on the first state- 
ment executed. 

STEP + 

Takes one optional argument, the number of statements to exe- 
cute. " 

BREAK . 

Takes one argument, which is an' editor address or interval at 

which to set a breakpoint (s) . 

KILL [ 

Takes one argument, an editor address or interval of break- 
point (s) to clear. 
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DISPLAY ] 

No arguments, lists all breakpoints. 

TRACE 5 

Takes two arguments, the first is an editor address. The trace 

breakpoint is set to this address and the program 'continues. 1 

The. second argument specifies the number of breakpoints to pass 

through. 

REPORT ( 

The user may specify that the value of any number of expres- 
sions be printed out at a break. Executing the REPORT command 
(takes no arguments) puts the debugger in a state where it is 
editing a line interpreted as a list of expressions separated 
by commas, whose values should be printed in the break mes- 
sage. 

NOTES: 

Whenever a program breaks, a break message is printed. The 
message will always start with the break address. The state- 
ment where the break occurred becomes the "current line" for 
the editor. To cause the source statement where the break oc- 
curred to be printed, use the L modifier 'with the program exe- 
cution commands (CONTINUE, STEP, TRACE, GOTO) . To suppress 
this, use. the Q ("quiet") modifier. 




A conditional breaking facility can be evoked in the following 
way: If at the time control is trans fered to the user program, 
a function with name BREAK' is defined, then the debugger will 
cause the program to be interpreted and the function BREAK' will 
be called after every statement is executed. Thus any user spe- 
cified condition can be tested for after every statement. 

To clear all break points use the modifier A with the KILL com- 
mand. 

To set or clear the trace break point use the modifier T with 
the BREAK or KILL command. 

To cause a break message at every breakpoint passed through use 
an E modifier with the STEP, CONTINUE, TRACE, and GOTO com- 
mands. To cause a break message only at the end use an N modi- 
fier, If no modifier is used, then the current mode will take 
effect. 

The user can specify that the GOTO, TRACE and CONTINUE com- 
mands only count the breakpoint on the current statement when 
counting the number of breakpoints passed through, by using the 
H modifier. The G modifier causes any breakpoint encountered 
to be counted. 

Notes on transfers of control to user program: The debugger 
has the facility for maintaining two programs at once. They 
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will hereafter be referred to as Task 1 and Task 2. The de- 
bugging may exist in a state called the zapped state (reset 
state) in which the call stack and hardware stack are initia- 
lized and the debugger is not aware of any tasks. Using a Z 
modifier with the mode command will zap the state. When a trans 
fer of control statement is executed a number of things must be 
considered before transfer of control is allowed: 

1) Do any statements or functions need recompiling? If so, 
they are recompiled. If the break statement has moved the 
P-counter must be changed accordingly. 

2) Is continuing legal? It isn't if the break statement has 
been modified or if the call stack cannot be unwound cor- 
rectly (see below) . 

3) Under what task should the program be run? 

4) Should the call stack be unwound and how much? 

Control can be transferee! to the program by the GOTO, CONTINUE, 
TRACE and STEP commands or by a direct statement. CONTINUE, 
TRACE and STEP are- legal only if 

a) a Task 1 program exists 

b) the P-counter is not in the middle of the statement 

Task 1 broke in, if the statement has been modified 
since the break. 
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To transfer control, first all modified statements or functions 
are recompiled. Then the action taken is determined by the 
following diagram. 



GOTO command or 
direct statement 
containing GOTO 
or RETURN 

otherwise 



call stack not 
empty 



unwind stack 
transfer con- 
trol as Task 1 



unwind stack 
transfer con- 
trol as Task 2 



call stack 
empty 



illegal 



transfer con- 
trol as Task 
1 with call 
stack set to 
(lumm^ local 
environment 



Unwind stack: The stack must be unwound far enough so that any 
call on the stack, in a statement that was subsequently 
modified, is removed from the stack. Once this is accom- 
plished the stack must be further unwound until the top 
function on the stack is the same as the current editor 
function. Unwinding the call stack requires user confirma- 
tion, If the stack is unwound the P-counter is set to the 
instruction after the top call on the unwound stack.. 

Run as Task 2: This means the state of Task 1 and the hard- 
ware stack pointer are saved. When Task 2 terminates for 
any reason the saved state and pointer are restored. 

EXAMINE / 

This command takes 0, I, or 2 arguments. 
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If 0, then the last quantity printed is printed again 
If 1, then the value of the expession is printed 
If 2, then the arguments are interpreted as bounds and 
everything in between is printed inclusive. 

The value of an expression can be printed in one of the fol- 
lowing formats 

signed integer I 

unsigned integer U 

real number R 

6-bit characters 6 

8-bit characters 8 

pointers 

(with B, S, I, ' U) P 

double precision 

(with R or 0) D 

complex X 

unsigned octal 

field descriptor F 

label or function B 



string 


S 


machine code 


M 


longlong 


W 



The type of the root operand in the parse tree will determine 
the format in which the value of an expression will be printed 
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unless a permanent mode is set. To suppress the permanent mode 
use a V modifier. 

Another format may be specified instead by using one of the 
above modifiers. The examine command will abort if what is 
requested doesn't make sense. 

For the two argument variety of the command both arguments must 
be references (in the sense of the SPL manual) i.e., be simple 
or have a principal operator which is indirection or sub- 
scripting, to be meaningful. Further, both arguments must spe- 
cify addresses in the same environment, i.e., the same common 
block or function, if they are both simple variables or sub- 
scripted variables. 

The two arguments otherwise are interpreted as absolute add- 
resses and the contents of the cells between the two addresses ! 
are printed in the specified mode. 

NEXT > 

This command takes one optional argument, n. It prints the next 
n quantities following the last quantity (location) printed. If; 
the argument is missing, it is taken to be 1. The format used 
for each quantity printed is taken from the symbol table unless 
overridden by modifiers in the command. Reaching the end of an 
environment (function, common block, absolute) terminates the 
command. • . ____, — _ 
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PREVIOUS < 

This command works the same as NEXT except that the n preceding, 

rather than following, quantities are printed. 

LEVEL t 

This command takes two arguments. The first specifies the num- 
ber of levels of local environment on the stack to jump hack. 
A negative number means go forward on the stack. The second . 
argument if specified is a function name. In this case jump 
n levels of that function. 

FIND ) 

Not yet specified. 

All state registers, etc., will be put in fixed places in the 

current global environment by the debugger and may be referred 

to with built-in symbols, to wit (in order): 

PC' program counter 
AR'N 

BR L 4~word accumulator 
CR' 

DRV 

XR' index register 

LR' local environment 

GR 1 global environment 

SR' status register 



#• 
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Mode 
. A 

B 

C 

D 

E 

F 
G 

H 

I 
J 
K 
L 

M 

m 

o 

p 

Q 

R 
S 
T 



Used with 



TABLE OF MODES 
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KILL 

EXAMINE, MODE 

EXAMINE, MODE 

GOTO, CONTINUE, STEP, 
TRACE, MODE 

EXAMINE, MODE 

GOTO, CONTINUE, 
TRACE, MODE 

GOTO, CONTINUE, 
TRACE, MODE 

EXAMINE, MODE 



GOTO, CONTINUE, 

STEP, TRACE, MODE 

EXAMINE, MODE . 

GOTO,, CONTINUE, 

STEP, TRACE, MODE 

EXAMINE, MODE- 

EXAMINE, MODE 

GOTO, CONTINUE, 

STEP, TRACE, MODE 

EXAMINE, MODE 

EXAMINE, MODE 

BREAK, KILL 



Meaning 

clear all breakpoints 

label or function 

double precision (R, 0) 

print message at every break 
point passed 

field descriptor 

all breakpoints encountered 
are counted 

only breakpoint on current 
statement is counted 

signed integer 



print source at break 

machine code 

print message only at end 

unsigned octal 

* 
po int ers ( B , S , I , U ) 

do not print source at break 

real number 

string 

set/clear trace breakpoin t 



&h 



u 

V 

w 

X 
Y 
Z 
6 
8 



EXAMINE, MODE 

EXAMINE, MODE 

EXAMINE, MODE 

EXAMINE, MODE 

MODE 

EXAMINE, MODE 

EXAMINE, MODE 
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unsigned integer 
suppress permanent mode 
longlong 
complex 

zap state 

6-bit characters 



8-bit characters 



